Format Specification Syntax: printf and wprintf functions

Describes the syntax for format specifications for printf, wprintf and related functions.

A format specification, consisting of optional and required elements, has the following form:

%[flags][width][.precision][opsize]type

Each element of the format specification is a character or number signifying a particular format option or conversion specifier. The required type character specifies the conversion to be applied to an argument. The optional argument list provides values for the width and precision fields. The simplest format specification contains only the percent sign and a type character (for example, %s). The optional fields, appearing before the required type character, control other aspects of the formatting.

These are the fields in a printf format specification:

Field Description

flags Optional character or characters that control output justification and sign printing, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.

width Optional number that specifies minimum number of output characters.

precision Optional number that specifies maximum number of characters printed for all or part of the output field, or minimum number of digits printed for integer values. See also: Precision specification.

opsize

Optional prefixes that determine the size of the argument expected, as shown below:

`h`	Used with the integer types d, i, u, o, x, and X to specify that the argument is short integer, or with u to specify short unsigned int. Used with %p, it indicates a 16-bit pointer, which is ignored. Used with %c or %C to specify that the argument is a single-byte character. An hc or hC specifier is synonymous with c in printf functions, and with C in wprintf functions. Used with %s or %S to specify that the argument is a single-byte character string. An hs or hS specifier is synonymous with s in printf functions, and with S in wprintf functions.
`l`	Used with d, i, u, o, x, and X types to specify that the argument is long integer, or with u to specify long unsigned integer; also used with e, E, f, g, and G types to specify double rather than float. Used with %p, it indicates a 48-bit segmented pointer, which is ignored.
`l, w`	Used with %c or %C to indicate that the argument is a wide character. An lc, lC, wc or wC is synonymous with C in printf functions, and with c in wprintf functions. Used with %s or %S to indicate that the argument is a wide character string. An ls, lS, ws or wS is synonymous with S in printf functions, and with s in wprintf functions.
`ll`, `L`, `I64`	Used with d, i, u, o, x and X types to specify a 64-bit integer.
`L`	Used with d, i, u, o, x and X types to specify a 64-bit integer, also used with e, E, f, g, and G types to specify long double.
`j`	Used with d, i, u, o, x and X types to specify that the argument is the size of intmax_t.
`t`	Used with d, i, u, o, x and X types to specify that the argument is the size of ptrdiff_t.
`z`	Used with d, i, u, o, x and X types to specify that the argument is the size of size_t.

type Required character that determines whether the associated argument is interpreted as a character, a string, or a number.

If a percent sign is followed by a character that has no meaning as a format field, the character is copied to stdout. For example, to print a percent-sign character, use %%.

Flag directives

In a format specification, the first optional field is flags. A flag directive is a character that specifies output justification and output of signs, blanks, leading zeros, decimal points, and octal and hexadecimal prefixes. More than one flag directive may appear in a format specification, and flags can appear in any order.

Flag	Description	Default
`-`	Left justify the result within the given field width.	Right justify.
`+`	Prefix the output value with a `+` or `-` sign if the output value is of a signed type.	`-` sign appears only for negative-signed values.
`0`	If width is prefixed with `0`, `0`s are added until the minimum width is reached. If `0` and `-` appear, the `0` is ignored. If `0` is specified with an integer format (`i`, `u`, `x`, `X`, `o`, `d`), the `0` is ignored.	No padding.
`blank (' ')`	Prefix the output value with a `blank` if the output value is signed and positive; the `blank` is ignored if both the `blank` and `+` flags appear.	No `blank` appears.
#	When used with the `o`, `x`, or `X` format, the `#` flag prefixes any non-0 output value with `0`, `0x`, or `0X`, respectively.	No blank appears.
	When used with the `e`, `E`, `f` or `F` format, the `#` flag forces the output value to contain a decimal point in all cases.	Decimal point appears only if digits follow it.
	When used with the `g` or `G` format, the `#` flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing 0s.	Decimal point appears only if digits follow it. Trailing 0s are truncated.
	Ignored when used with `c`, `d`, `i`, `u`, or `s`.

Width specification

The width specification is a non-negative decimal integer that controls the minimum number of printed characters. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values, depending on whether the - flag is specified until the minimum width is reached. If width is prefixed with 0, printf adds 0s until the minimum width is reached (not useful for left-justified numbers).

The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or width is not given, all characters of the value are printed, subject to the precision specification.

The width specification may be an asterisk (*), in which case an integer argument from the argument list supplies the value. The width specification must precede the value being formatted in the argument list. A nonexistent or small field width does not truncate a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.

Precision specification

The precision specification specifies a non-negative decimal integer, preceded by a period (.), which specifies the number of characters to print, the number of decimal places, or the number of significant digits. The precision specification can cause truncation of the output value, or rounding in the case of a double value. If printf specifies precision is 0 and the value to convert is 0, the result is no characters output, as shown below:

printf( "%.0d", 0 );  /* No characters output */

The precision specification may be an asterisk (*), in which case an integer argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list.

The interpretation of the precision value and the default precision (if omitted) depend on the type, as shown below:

Type	Description	Default
`d`, `i`, `u`, `o`, `O`, `x`, `X`, `b`, `B`	The precision specifies the minimum number of digits to print. If the number of digits in the argument is less than precision, the output value is padded on the left with 0s. The value is not truncated when the number of digits exceeds precision. If precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.	If precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.
`D`	The precision specifies the number of bytes to dump as hex numbers.	Default precision is 16.
`e`, `E`	The precision specifies the number of digits to print after the decimal point. The last printed digit is rounded.	Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed.
`f`, `F`	The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.	Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.
`g`, `G`	The precision specifies the maximum number of significant digits printed. If specified as 0, treated as 1.	Six significant digits are printed, with any trailing 0s truncated.
`c, C`	The precision has no effect.	Character is printed.
`s, S`	The precision specifies the maximum number of characters to print. Characters in excess of precision are not printed.	Characters are printed until a null character is encountered.

If the argument corresponding to a double specifier is infinite, indefinite, or not a number (NAN), printf gives this output:

Value	Output
+ infinity	1.#INF`random-digits`
- infinity	-1.#INF`random-digits`
Indefinite	`digit.#INDrandom-digits`
Not a number (NAN)	`digit.#NANrandom-digits`

Type field characters

The type character is the only required format field for printf. It appears after any optional format fields and determines how the associated argument is interpreted.

Char	Argument	Output format
`b`	Integer	Unsigned binary integer.
`d`	Integer	Signed decimal integer.
`D`	Bytes	Hex dump assistance. Requires two arguments, a BYTE * pointer and a char * string. The memory pointed to by the pointer is output two hex digits at a time with the text at the string being printed between each value. Example: printf("out: %4D\n", "AAAA", ":"); results in: out: 41:41:41:41
`i`	Integer	Signed decimal integer.
`u`	Integer	Unsigned decimal integer.
`o`	Integer	Unsigned octal integer.
`x`	Integer	Unsigned hexadecimal integer, using `abcdef`.
`X`	Integer	Unsigned hexadecimal integer, using `ABCDEF`.
`f`	Floating-point	Signed value having the form `[-]dddd.dddd`, where `dddd` is one or more decimal digits, depending upon the magnitude of the number, and the requested precision.
`e`	Floating-point	Signed value having the form `[-]d.dddd e [sign]ddd`, where `d` is a single decimal digit, `dddd` is one or more decimal digits, `ddd` is exactly three decimal digits, and `sign` is + or -.
`E`	Floating-point	Same as the e format, except that `E` introduces the exponent.
`g`	Floating-point	Signed value printed in `f` or `e` format (the one most compact for the given value and precision). `e` is used only when the exponent of the value is less than -4 or greater than or equal to the precision. Trailing 0s are truncated and the decimal point appears only if any digits follow it.
`G`	Floating-point	Same as the `g` format, except that `G` introduces the exponent (where appropriate).
`c`	Character	When used with `printf` functions, specifies a single-byte character; when used with `wprintf` functions, specifies a wide character.
`C`	Character	When used with `printf` functions, specifies a wide character; when used with `wprintf` functions, specifies a single-byte character.
`s`	String	When used with printf functions, specifies a single-byte character string. When used with wprintf functions, specifies a wide-character string. Characters are output up to the first null character or until the precision value is reached.
S	String	When used with printf functions, specifies a wide-character string. When used with wprintf functions, specifies a single-byte character string. Characters are output up to the first null character or until the precision value is reached.
`n`	Pointer to integer	Points to number of characters successfully written so far to the stream or buffer; this value is stored in the integer whose address is given as the argument.
`p`	Pointer type	Prints the address pointed to by the argument.